// Flickr auth and export support
// Copyright 2006 (C) Ralph Thomas

#ifndef MISSION_APPS_PHOTO_FLICKR_H
#define MISSION_APPS_PHOTO_FLICKR_H

#include <string>
#include <iostream>

namespace flickr {
	//
	/// Request a "frob" (what does that mean?) from Flickr; it's used
	/// to identify a login request. Once we have a token we don't need
	/// it any more, all subsequent calls use the token.
	///
	/// This function uses HTTP to flickr, and thus will be slow. It
	/// will throw an exception in the event of failure.
	///
	/// \return	a "frob" to identify a login request.
	//
	std::string get_frob();
	//
	/// Return the URL that the user needs to visit to authenticate
	/// his/her flickr session.
	///
	/// This function does *NOT* use the network.
	///
	/// \param	frob	the frob to build the request with.
	/// \return	the URL to authorize this app at.
	//
	std::string get_auth_url( const std::string& frob );
	//
	/// Once the app has been authorized, a token can be requested.
	/// This function will attempt to fetch a token using the given
	/// frob, which should have been authorized by the user visiting
	/// the URL returned by get_auth_url.
	///
	/// If possible, the token should be stored and used next time,
	/// to avoid sending the user to the auth page every time.
	///
	/// This function uses HTTP to flickr, and thus will be slow. It
	/// will throw an exception in the event of failure.
	///
	/// \param	frob	the frob to get the token for.
	/// \return	the token to use on subsequent calls to the
	///		flickr API.
	//
	std::string get_token( const std::string& frob );
	//
	/// Check if the given token is valid. This function uses HTTP to
	/// flickr and thus will be slow.
	///
	/// \param	token	the token to check.
	/// \return	true if the token is valid, false otherwise.
	//
	bool check_token( const std::string& token );
	//
	/// Upload a photo to Flickr using the given token for authentication.
	/// This function HTTP POSTs the image to flickr, and thus could take
	/// a while.
	///
	/// \param	token		authenticated, valid token.
	/// \param	title		the title of the photo (if any).
	/// \param	description	the description of the photo (if any).
	/// \param	tags		a space separated list of tags for the photo.
	/// \param	is_public	true if the image is to be public.
	/// \param	is_friend	true if the image is for friends.
	/// \param	is_family	true if the image is for family.
	/// \param	photo		an open std::streambuf of the photo.
	///
	/// If this function fails then it throws an exception.
	//
	void upload_photo( const std::string& token, const std::string& title, const std::string& description, const std::string& tags, bool is_public, bool is_friend, bool is_family, std::streambuf& photo );
}

#endif

